home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / SetResult.man < prev    next >
Encoding:
Text File  |  1992-11-09  |  9.4 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_SetResult         C Library Procedures          Tcl_SetResult
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_SetResult,     Tcl_AppendResult,      Tcl_AppendElement,
  12.      Tcl_ResetResult - manipulate Tcl result string
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ttccll..hh>>
  16.  
  17.      TTccll__SSeettRReessuulltt(_i_n_t_e_r_p, _s_t_r_i_n_g, _f_r_e_e_P_r_o_c)                       |
  18.  
  19.      TTccll__AAppppeennddRReessuulltt((_i_n_t_e_r_p, _s_t_r_i_n_g, _s_t_r_i_n_g, ... , ((cchhaarr **)) NNUULLLL)
  20.  
  21.      TTccll__AAppppeennddEElleemmeenntt(_i_n_t_e_r_p, _s_t_r_i_n_g, _n_o_S_e_p)                      |
  22.  
  23.      TTccll__RReesseettRReessuulltt(_i_n_t_e_r_p)                                       |
  24.  
  25.      TTccll__FFrreeeeRReessuulltt(_i_n_t_e_r_p)                                        |
  26.  
  27. AARRGGUUMMEENNTTSS
  28.      Tcl_Interp     *_i_n_t_e_r_p    (out)     Interpreter whose result
  29.                                          is to be modified.
  30.  
  31.      char           *_s_t_r_i_n_g    (in)      String value  to  become
  32.                                          result  for _i_n_t_e_r_p or to
  33.                                          be appended to  existing
  34.                                          result.
  35.  
  36.      Tcl_FreeProc   _f_r_e_e_P_r_o_c   (in)      Address of procedure  to  |
  37.                                          call  to release storage  |
  38.                                          at      _s_t_r_i_n_g,       or  |
  39.                                          TTCCLL__SSTTAATTIICC, TTCCLL__DDYYNNAAMMIICC,  |
  40.                                          or TTCCLL__VVOOLLAATTIILLEE.          |
  41.  
  42.      int            _n_o_S_e_p      (in)                                     ||
  43.                                          If  non-zero  then don't  |
  44.                                          output a space character  |
  45.                                          before   this   element,  |
  46.                                          even  if   the   element  |
  47.                                          isn't the first thing in  |
  48.                                          the result string.
  49. _________________________________________________________________
  50.  
  51.  
  52. DDEESSCCRRIIPPTTIIOONN
  53.      The procedures described here are utilities for setting  the
  54.      result/error string in a Tcl interpreter.
  55.  
  56.      TTccll__SSeettRReessuulltt arranges for _s_t_r_i_n_g to be  the  return  string
  57.      for  the current Tcl command in _i_n_t_e_r_p, replacing any exist-
  58.      ing result.  If _f_r_e_e_P_r_o_c is TTCCLL__SSTTAATTIICC it means that  _s_t_r_i_n_g  |
  59.      refers  to  an area of static storage that is guaranteed not  |
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_SetResult         C Library Procedures          Tcl_SetResult
  71.  
  72.  
  73.  
  74.      to be modified until at least the next call to TTccll__EEvvaall.  If  |
  75.      _f_r_e_e_P_r_o_c  is  TTCCLL__DDYYNNAAMMIICC it means that _s_t_r_i_n_g was allocated  |
  76.      with a call to mmaalllloocc(()) and is now the property of  the  Tcl  |
  77.      system.  TTccll__SSeettRReessuulltt will arrange for the string's storage  |
  78.      to be released by  calling  ffrreeee(())  when  it  is  no  longer  |
  79.      needed.   If  _f_r_e_e_P_r_o_c  is TTCCLL__VVOOLLAATTIILLEE it means that _s_t_r_i_n_g  |
  80.      points to an area of memory that is likely to be overwritten  |
  81.      when TTccll__SSeettRReessuulltt returns (e.g. it points to something in a  |
  82.      stack frame).  In this case TTccll__SSeettRReessuulltt will make  a  copy  |
  83.      of  the  string in dynamically allocated storage and arrange  |
  84.      for the copy to be the return string  for  the  current  Tcl  |
  85.      command.                                                      |
  86.  
  87.      If _f_r_e_e_P_r_o_c isn't one of the values TTCCLL__SSTTAATTIICC, TTCCLL__DDYYNNAAMMIICC,  |
  88.      and TTCCLL__VVOOLLAATTIILLEE, then it is the address of a procedure that  |
  89.      Tcl should call to free the string.   This  allows  applica-  |
  90.      tions  to  use non-standard storage allocators.  When Tcl no  |
  91.      longer needs the  storage  for  the  string,  it  will  call  |
  92.      _f_r_e_e_P_r_o_c.   _F_r_e_e_P_r_o_c  should  have arguments and result that  |
  93.      match the type TTccll__FFrreeeePPrroocc:                                  |
  94.  
  95.           typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);               |
  96.  
  97.      When _f_r_e_e_P_r_o_c is called, its _b_l_o_c_k_P_t_r will  be  set  to  the  |
  98.      value of _s_t_r_i_n_g passed to TTccll__SSeettRReessuulltt.
  99.  
  100.      If  _s_t_r_i_n_g  is  NNUULLLL,   then   _f_r_e_e_P_r_o_c   is   ignored   and
  101.      TTccll__SSeettRReessuulltt re-initializes _i_n_t_e_r_p's result to point to the
  102.      pre-allocated result area,  with  an  empty  string  in  the
  103.      result area.
  104.  
  105.      If TTccll__SSeettRReessuulltt is called at a time  when  _i_n_t_e_r_p  holds  a  |
  106.      result,  TTccll__SSeettRReessuulltt does whatever is necessary to dispose  |
  107.      of the old result  (see  the  TTccll__IInntteerrpp  manual  entry  for  |
  108.      details on this).
  109.  
  110.      TTccll__AAppppeennddRReessuulltt makes it easy to build up  Tcl  results  in
  111.      pieces.   It  takes each of its _s_t_r_i_n_g arguments and appends
  112.      them in order to the current result associated with  _i_n_t_e_r_p.  |
  113.      If the result is in its initialized empty state (e.g. a com-  |
  114.      mand procedure was just invoked or TTccll__RReesseettRReessuulltt was  just  |
  115.      called),  then  TTccll__AAppppeennddRReessuulltt sets the result to the con-  |
  116.      catenation of its _s_t_r_i_n_g arguments.  TTccll__AAppppeennddRReessuulltt may be
  117.      called  repeatedly  as  additional  pieces of the result are
  118.      produced.  TTccll__AAppppeennddRReessuulltt takes care of  all  the  storage
  119.      management  issues associated with managing _i_n_t_e_r_p's result,
  120.      such as allocating a larger result area if  necessary.   Any
  121.      number  of  _s_t_r_i_n_g arguments may be passed in a single call;
  122.      the last argument in the list must be a NULL pointer.
  123.  
  124.      TTccll__AAppppeennddEElleemmeenntt is similar to TTccll__AAppppeennddRReessuulltt in that  it  |
  125.      allows   results   to  be  built  up  in  pieces.   However,  |
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_SetResult         C Library Procedures          Tcl_SetResult
  137.  
  138.  
  139.  
  140.      TTccll__AAppppeennddEElleemmeenntt takes only a single _s_t_r_i_n_g argument and it  |
  141.      appends  that argument to the current result as a proper Tcl  |
  142.      list element.  TTccll__AAppppeennddEElleemmeenntt adds backslashes or  braces  |
  143.      if necessary to ensure that _i_n_t_e_r_p's result can be parsed as  |
  144.      a list and that _s_t_r_i_n_g will be extracted as  a  single  ele-  |
  145.      ment.  Under normal conditions, TTccll__AAppppeennddEElleemmeenntt will add a  |
  146.      space character to _i_n_t_e_r_p's result just  before  adding  the  |
  147.      new  list  element,  so that the list elements in the result  |
  148.      are properly separated.   However,  if  _i_n_t_e_r_p's  result  is  |
  149.      empty  when  TTccll__AAppppeennddEElleemmeenntt  is  called,  or if the _n_o_S_e_p  |
  150.      argument is 1, then no space is added.                        |
  151.  
  152.      TTccll__RReesseettRReessuulltt clears the result for  _i_n_t_e_r_p,  freeing  the  |
  153.      memory  associated with it if the current result was dynami-  |
  154.      cally allocated.  It leaves the result in  its  normal  ini-  |
  155.      tialized  state  with  _i_n_t_e_r_p->_r_e_s_u_l_t  pointing  to a static  |
  156.      buffer containing TTCCLL__RREESSUULLTT__SSIIZZEE characters, of  which  the  |
  157.      first  character  is  zero.  TTccll__RReesseettRReessuulltt also clears the  |
  158.      error    state    managed    by     TTccll__AAddddEErrrroorrIInnffoo     and  |
  159.      TTccll__SSeettEErrrroorrCCooddee.                                             |
  160.  
  161.      TTccll__FFrreeeeRReessuulltt is a macro that performs part of the work  of  |
  162.      TTccll__RReesseettRReessuulltt.   It  frees  up  the memory associated with  |
  163.      _i_n_t_e_r_p's result and sets _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to  zero,  but  it  |
  164.      doesn't   change   _i_n_t_e_r_p->_r_e_s_u_l_t   or  clear  error  state.  |
  165.      TTccll__FFrreeeeRReessuulltt is most commonly used  when  a  procedure  is  |
  166.      about to replace one result value with another.
  167.  
  168.  
  169. SSEEEE AALLSSOO
  170.      Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  171.  
  172.  
  173. KKEEYYWWOORRDDSS
  174.      append, command, element, list, result, return value, inter-
  175.      preter
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.